Add PDF features to improve usability #58
Conversation
|
With MSYS2 the PDF is in letter format whereas with Linux it is in A4. And indeed the paper size has something to do with the wrong destination position. I changed the paper size via two groff command line options described here: Here are my test results, both with MSYS2 and Linux:
Should I set A4 explicitly? Then the problem with link destination would be fixed and the PDFs in Win64 and Linux release files would also be in the same paper size. |
|
Rebased on master to modify the new doc/man5/srec_os65a.5 |
|
Three tasks done with these new five commits. Rebase and cleanup will happen later. Have to investigate about the wrong placement of srec_wilson(5) PDF outline entry. |
If this is still an open question, then yes set to A4. This was an oversight on my part when getting the MSYS2 build up and running. |
The latest commit "Explicitly set a consistent paper size" addressed this and set it to A4. But thanks for the reply and agreement.
The A4/letter inconsistency was already present in the 1.64 release from 2014, I have checked right now. |
|
This is looking great Marcus! I'll wait until you hit "ready for review" before I start looking properly (but please don't feel rushed). Given the number commits, I'm happy to squash but if you'd prefer to rebase into a few select/logical commits, that works too. |
|
I'll definitely rebase into a few commits, I'm a clean-history-fanatic. It's Markus with k, the c just comes from the "cow" part of my username which I'm not a big fan of anymore :-/ |
|
Sounds good and thank you Markus for correcting me on the spelling. I did take my spelling cue from 'cow" so I'm guessing I'm not the first to make that mistake at least. |
Only in doc/man1/srec_license.1 there is no .SH macro, so put it below
.TH (which in most cases is placed directly before .SH anyway).
Preparation for extending the .XX macro to also generate PDF outline
entries additionally to the TOC entries. To get the link target at the
correct position.
This change also has the effect to remove the probably unintended empty
line at each place where this ".if require_index \{ .XX ... .\}"
construct was used, in most cases after the NAME section.
The TOC itself is unchanged in principle, merely line numbers have
changed because of reduced number of pages (due to removed empty lines).
Otherwise it would be wrongly displayed as "[hy]" in the PDF outline. But it's not even typographically wrong now, see https://man7.org/linux/man-pages/man7/groff_char.7.html For best results in roff systems, use the "-" character in input outside an escape sequence only to mean a hyphen, as in the phrase "long-term".
Use the "pdfmark" macro package. The metadata can be viewed via document properties of PDF readers.
Also using the "pdfmark" marco package as for PDF metadata. The outline can normally be accessed via sidebar of PDF readers.
This is only a recommendation, PDF viewers may ignore this setting.
To be independent of system settings and for a reproducible output across different systems. Additionally, inconsistent groff options (e.g. -dpaper=letter -P-pa4), resulting from implicit configuration, lead to wrong target position of the PDF outline links. See also: https://www.gnu.org/software/groff/manual/html_node/Paper-Size.html The content in the resulting PDF documents now have a different layout compared to the latest release (Linux build): It goes further down, but less far to the right.
Fixes CSpell errors "Unknown word" in the following files: doc/CMakeLists.txt doc/etc/ref-toc.so doc/etc/reference.man Put "pdfmark" itself to names.txt instead of to the allowed words in cspell.config.yaml because it is the name of a macro package and "groff" is listed here as well.
|
Finally ready for review, two notes from my side:
|
I created those dictionaries for "non-fixable" words: All other words, which I had not analyzed in detail, are excluded in the top-level |
PDF metadata and PDF outline (navigation in the side bar) have been added.
Tasks:
It is at the beginning, but should be at the end. Caused by psselect command in page_select.sh (which moves the TOC pages from the end to page 3).
They are correct for my MSYS2 build, but too far down for my Linux build. They point to around e.g. DESCRIPTION instead of to NAME. Can you reproduce it? Maybe it's just an oddity with my Linux system.
Maybe just enclose it with ".if require_index" as it is done for the .XX macro. Strangely when changing ".nr equire_index 1" (yes, looks like a typo, but seems to be intention) in doc/etc/reference.man to ".nr require_index 1" then the affected TOC entries are missing. I would have expected opposite behaviour.
At least in the first step. Currently also README.pdf gets an outline (with only one entry, better to say without the last entry, because of missing .pdfsync command).
(Partially) implements the second task of #1.